Skip to main content

Single sign-on (SSO)

UniFi supports single sign-on (SSO) which means users don't have to remember separate credentials for each different piece of software they use, so making for a better user experience and simplifying administration. Some common methods of using SSO within UniFi are documented below.

Microsoft 365​

If your users have Microsoft 365 accounts then you just need to make 'Microsoft' their provider in the 'User Management' screen. Their Microsoft 365 credentials should then take them straight into UniFi as long as their UniFi email address matches their Microsoft 365 user name simply by clicking on the 'Sign in with Microsoft' button - permissions will be requested the first time they do this, these can be revoked from the Microsoft Azure portal if this is ever required.

Security Assertion Markup Language (SAML)​

UniFi also supports single sign-on via SAML. This can be via Microsoft Azure Active Directory or non-Microsoft authentication providers such as Okta. Details of both of these options are below.

info

To complete any of the processes below you will need to be logged in to UniFi as the 'system' user. This is a special user that can view and edit sensitive information.

SAML in Azure Active Directory​

If you use Microsoft Azure, Security Assertion Markup Language (SAML) can be used with Microsoft Azure Active Directory (Azure AD) to enable SSO. This involves configuring an enterprise application in Azure AD to act as the Identity Provider (IdP) for a Service Provider (SP), in this case UniFi.

In the Azure portal at https://portal.azure.com, with an account that has the appropriate privileges create a new enterprise application from the 'Azure Active Directory' > 'Manage' > 'Enterprise Applications' page. Select 'Create your own application', give it a name (e.g. 'UniFi'), select 'Integrate any other application you don't find in the gallery' and click 'Create'.

Once created you can navigate to the application page and under the 'Manage' section click Single Sign-On and chose the SAML option. The settings you will need from UniFi are as follows:

  • Identifier (Entity ID) - This will be https://tenantcode.unifiplatform.com. Your tenant code can be obtained from within UniFi under 'Settings' > 'Organisations and Divisions' on the 'General Information' tab.

  • Reply URL (ACS URL) - This is available under the 'SAML Configuration' tab of the above section and will usually be in the format https://tenantcode.unifiplatform.com/auth/saml2. This is often called the Assertion Consumer Service (ACS URL).

  • Sign-on URL - The URL your users will be redirected to after logging in through Azure AD, usually the same as the identifier e.g. https://tenantcode.unifiplatform.com. This is essential the app home page where users will be redirected to after logging in.

You now need to enter some information in UniFi from the app created in Azure AD. This is all within the UniFi 'Settings' > 'Organisations & Divisions' > 'SAML Configuration' tab.

  • Azure AD Identifier - Copy this into the 'Identifier (Entity ID)' field in UniFi. This is the globally unique identifier for Azure AD as the identity provider.

  • Azure AD SSO URL - Copy this into the 'Login URL' field in UniFi. This will probably be in the format https://login.microsoftonline.com/*tenantcode*/saml2.

  • Signing Certificate - Download this from the 'SAML Certificates' section in Azure in Base64 format. Copy the text into the 'Certificate' box in UniFi.

You should now be ready to test logging on via SAML.

Okta SAML Single Sign-On​

UniFi also supports the Okta Single Sign-On service. In order to configure this an Okta administrator should log in to the Okta Admin Console and create an 'App Integration' with the sign-on method of 'SAML 2.0'. Enter an app name and set the optional visibility and then configure the SAML settings as follows:

  • Single Sign-On URL (ACS URL) - This can be obtained from within UniFi, as the 'system' user go to 'Organisation' > 'SAML Configuration' and copy the 'Reply URL (Assertion Consumer Service URL)' from here.

  • Audience URI (SP Entity URI) - This will be https://tenantcode.unifiplatform.com. Your tenant code can be obtained from within UniFi under 'Settings' > 'Organisations and Divisions' on the 'General Information' tab.

  • Name ID Format - Usually select 'EmailAddress' here unless you have a configuration where you are not wanting to link email addresses in UniFi to a SSO username in which case you can select 'Persistent' for a non-changing identifier.

  • Application username - This can be the users email if that is the name ID format selected above or username.

From within the Okta sign-on tab you can find the following information, which you will now need to copy back into the 'SAML Configuration' tab in UniFi:

  • Identity Provider Single Sign-On URL (SSO URL) - Copy this into the 'Login URL' field in UniFi.

  • Identity Provider Issuer - Copy this into the 'identifier (Entity ID)' field in UniFi.

  • X.509 Certificate - Copy this into the UniFi 'Certificate' field.

You should now be ready to test logging on via SAML.